Node / meshtastic / Meshtastic-Android / files / core / ble / src / commonMain / kotlin / org / meshtastic / core / ble / BleConnection.kt

Displaying Raw • Download

T8b949e/*

* Copyright (c) 2026 Meshtastic LLC

*

* This program is free software: you can redistribute it and/or modify

* it under the terms of the GNU General Public License as published by

* the Free Software Foundation, either version 3 of the License, or

* (at your option) any later version.

*

* This program is distributed in the hope that it will be useful,

* but WITHOUT ANY WARRANTY; without even the implied warranty of

* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

* GNU General Public License for more details.

*

* You should have received a copy of the GNU General Public License

* along with this program. If not, see <https://www.gnu.org/licenses/>.

*/

Tff7b72package T7ee787org.meshtastic.core.ble

Tff7b72import T7ee787kotlinx.coroutines.CoroutineScope

Tff7b72import T7ee787kotlinx.coroutines.flow.Flow

Tff7b72import T7ee787kotlinx.coroutines.flow.StateFlow

Tff7b72import T7ee787kotlinx.coroutines.flow.onStart

Tff7b72import T7ee787kotlin.time.Duration

Tff7b72import T7ee787kotlin.time.Duration.Companion.seconds

Tff7b72import T7ee787kotlin.uuid.Uuid

T8b949e/** Represents the type of write operation. */

Tff7b72enum Tff7b72class T56d364BleWriteType Tb4b4b4{

Te6edf3WITH_RESPONSETb4b4b4,

Te6edf3WITHOUT_RESPONSETb4b4b4,

Tb4b4b4}

T8b949e/** Identifies a characteristic within a profiled BLE service. */

Tff7b72data Tff7b72class T56d364BleCharacteristicTb4b4b4(Tff7b72val Te6edf3uuidTb4b4b4: Te6edf3UuidTb4b4b4)

T8b949e/** Safe ATT payload length when MTU negotiation is unavailable (23-byte ATT MTU minus 3-byte header). */

Tff7b72const Tff7b72val Te6edf3DEFAULT_BLE_WRITE_VALUE_LENGTH Tff7b72= T79c0ff2T79c0ff0

T8b949e/** Encapsulates a BLE connection to a [BleDevice]. */

Tff7b72interface T56d364BleConnection Tb4b4b4{

T8b949e/** The currently connected [BleDevice], or null if not connected. */

Tff7b72val Te6edf3deviceTb4b4b4: Te6edf3BleDevice?

T8b949e/**

* A flow of the current device. [StateFlow] semantics: replays the latest value to new collectors and conflates

* rapid updates.

*/

Tff7b72val Te6edf3deviceFlowTb4b4b4: Te6edf3StateFlowTff7b72<Te6edf3BleDevice?Tff7b72>

T8b949e/**

* A flow of [BleConnectionState] changes. [StateFlow] semantics ensure the latest state is always observable and

* distinct-equals deduplication avoids spurious re-emissions.

*/

Tff7b72val Te6edf3connectionStateTb4b4b4: Te6edf3StateFlowTff7b72<Te6edf3BleConnectionStateTff7b72>

T8b949e/** Connects to the given [BleDevice]. */

Tff7b72suspend Tff7b72fun Td2a8ffconnectTb4b4b4(Te6edf3deviceTb4b4b4: Te6edf3BleDeviceTb4b4b4)

T8b949e/** Connects to the given [BleDevice] and waits for a terminal state or [timeout]. */

Tff7b72suspend Tff7b72fun Td2a8ffconnectAndAwaitTb4b4b4(Te6edf3deviceTb4b4b4: Te6edf3BleDeviceTb4b4b4, Te6edf3timeoutTb4b4b4: Te6edf3DurationTb4b4b4)Tb4b4b4: Te6edf3BleConnectionState

T8b949e/** Disconnects from the current device. */

Tff7b72suspend Tff7b72fun Td2a8ffdisconnectTb4b4b4(Tb4b4b4)

T8b949e/**

* Executes [setup] after the requested BLE profile is available. This is shared by radio, OTA, and DFU flows, so

* implementations should keep profile-entry setup bounded and avoid transfer-hot-path work here when a caller can

* reuse an already discovered [BleService].

*/

Tff7b72suspend Tff7b72fun Tff7b72<Te6edf3TTff7b72> Td2a8ffprofileTb4b4b4(

Te6edf3serviceUuidTb4b4b4: Te6edf3UuidTb4b4b4,

Te6edf3timeoutTb4b4b4: Te6edf3Duration Tff7b72= T79c0ff3T79c0ff0.Te6edf3secondsTb4b4b4,

Te6edf3setupTb4b4b4: Te6edf3suspend Te6edf3CoroutineScopeTb4b4b4.Tb4b4b4(Te6edf3BleServiceTb4b4b4) Tff7b72-Tff7b72> Te6edf3TTb4b4b4,

Tb4b4b4)Tb4b4b4: Te6edf3T

T8b949e/** Returns the maximum write value length for the given write type, or `null` if unknown. */

Tff7b72fun Td2a8ffmaximumWriteValueLengthTb4b4b4(Te6edf3writeTypeTb4b4b4: Te6edf3BleWriteTypeTb4b4b4)Tb4b4b4: Tffa657Int?

T8b949e/**

* Asks the platform to switch to a high-throughput / low-latency BLE connection priority for the duration of the

* connection. Used by latency-sensitive flows like firmware updates. Returns `true` if the request was issued.

* Default implementation returns `false` for platforms that don't support it.

*/

Tff7b72fun Td2a8ffrequestHighConnectionPriorityTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657Boolean Tff7b72= Tff7b72false

T8b949e/**

* Requests the platform to return to balanced BLE connection priority (default ~30–50 ms interval). Call after

* latency-sensitive operations (initial config drain, DFU) to reduce ongoing battery draw. Default implementation

* returns `false` for platforms that don't support it.

*/

Tff7b72fun Td2a8ffrequestBalancedConnectionPriorityTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657Boolean Tff7b72= Tff7b72false

T8b949e/**

* Clears the platform's cached GATT service table for the connected peripheral. Necessary when a device reboots

* into a different GATT profile (e.g., ESP32 OTA loader) on the same BLE MAC. Returns `true` if the cache was

* invalidated. Default implementation returns `false` for platforms without a service cache.

*/

Tff7b72fun Td2a8ffinvalidateServiceCacheTb4b4b4(Tb4b4b4)Tb4b4b4: Tffa657Boolean Tff7b72= Tff7b72false

Tb4b4b4}

T8b949e/** Represents a BLE service for commonMain. */

Tff7b72interface T56d364BleService Tb4b4b4{

T8b949e/** Creates a handle for a characteristic belonging to this service. */

Tff7b72fun Td2a8ffcharacteristicTb4b4b4(Te6edf3uuidTb4b4b4: Te6edf3UuidTb4b4b4)Tb4b4b4: Te6edf3BleCharacteristic Tff7b72= Te6edf3BleCharacteristicTb4b4b4(Te6edf3uuidTb4b4b4)

T8b949e/** Returns true when the characteristic is present on the connected device. */

Tff7b72fun Td2a8ffhasCharacteristicTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4)Tb4b4b4: Tffa657Boolean

T8b949e/** Returns the UUIDs of all characteristics discovered for this service. Empty for non-Kable platforms. */

Tff7b72fun Td2a8ffdiscoveredCharacteristicUuidsTb4b4b4(Tb4b4b4)Tb4b4b4: Te6edf3ListTff7b72<Te6edf3UuidTff7b72> Tff7b72= Te6edf3emptyListTb4b4b4(Tb4b4b4)

T8b949e/** Observes notifications/indications from the characteristic. */

Tff7b72fun Td2a8ffobserveTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4)Tb4b4b4: Te6edf3FlowTff7b72<Te6edf3ByteArrayTff7b72>

T8b949e/**

* Observes notifications/indications from the characteristic with an [onSubscription] action that fires **after**

* notifications are enabled (CCCD written).

*

* The [onSubscription] is re-invoked on every reconnect while the returned [Flow] is active. The default

* implementation invokes [onSubscription] eagerly on flow start so non-Kable implementations still signal

* readiness.

*/

Tff7b72fun Td2a8ffobserveTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4, Te6edf3onSubscriptionTb4b4b4: Te6edf3suspend Tb4b4b4(Tb4b4b4) Tff7b72-Tff7b72> Tffa657UnitTb4b4b4)Tb4b4b4: Te6edf3FlowTff7b72<Te6edf3ByteArrayTff7b72> Tff7b72=

Te6edf3observeTb4b4b4(Te6edf3characteristicTb4b4b4)Tb4b4b4.Te6edf3onStart Tb4b4b4{ Te6edf3onSubscriptionTb4b4b4(Tb4b4b4) Tb4b4b4}

T8b949e/** Reads the characteristic value once. */

Tff7b72suspend Tff7b72fun Td2a8ffreadTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4)Tb4b4b4: Te6edf3ByteArray

T8b949e/** Returns the preferred write type for the characteristic on this platform/device. */

Tff7b72fun Td2a8ffpreferredWriteTypeTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4)Tb4b4b4: Te6edf3BleWriteType

T8b949e/** Writes a value to the characteristic using the requested BLE write type. */

Tff7b72suspend Tff7b72fun Td2a8ffwriteTb4b4b4(Te6edf3characteristicTb4b4b4: Te6edf3BleCharacteristicTb4b4b4, Te6edf3dataTb4b4b4: Te6edf3ByteArrayTb4b4b4, Te6edf3writeTypeTb4b4b4: Te6edf3BleWriteTypeTb4b4b4)

Tb4b4b4}